feat(hub): whole-package zip download + file list on the agent page - #1843

🔴 Critical

package_files is dropped on the real release path → feature never renders (workers/agent-hub/src/publish.ts:262)

package_files is stored only inside the if (!versionExists) block:

if (!versionExists) {
  ...
  if (packageFilesText != null) {
    await env.BUCKET.put(packageFilesKey(...), packageFilesText, {...});
  }
}

versionExists = Boolean(existing?.versions[manifest.version]) (publish.ts:200). In the release workflow the version is created by the binaries publish step (release_agent_email.yml:457, same ${MANIFEST} → same version, also where README/CHANGELOG ride in). The new zip + package_files POST runs after that (release_agent_email.yml:531), so by then versionExists === true and the whole !versionExists block is skipped — package_files is never written.

Downstream consequence: readPackageFiles returns null (storage.ts:517), so toIndexEntry's packageFiles && zip guard yields pkg = undefined (catalog.ts:382), and packageDownloadUrl / the {agent.package && pkgUrl && (...)} block render nothing. The zip artifact itself is still stored (the BUCKET.put at publish.ts:241 is unconditional), so the download exists at its URL — but the page that's supposed to surface it never does. Silent no-op, no error — the opposite of the "fail loudly" rule.

README/CHANGELOG are correctly gated to first-publish because they're sent on that first call. package_files is structurally different: it can only arrive on a later publish to an existing version, so it must not share that gate. Suggested fix — move the store out of the !versionExists block (a later binary publish passes no package_files, so packageFilesText is null there and won't clobber):

  if (!versionExists) {
    await env.BUCKET.put(rawManifestKey(manifest.id, manifest.version), manifestText, {
      httpMetadata: { contentType: "application/x-yaml; charset=utf-8" },
    });
    if (readmeText != null) {
      await env.BUCKET.put(readmeKey(manifest.id, manifest.version), readmeText, {
        httpMetadata: { contentType: "text/markdown; charset=utf-8" },
      });
    }
    if (changelogText != null) {
      await env.BUCKET.put(changelogKey(manifest.id, manifest.version), changelogText, {
        httpMetadata: { contentType: "text/markdown; charset=utf-8" },
      });
    }
  }
  // The whole-package file list rides with the .zip artifact, which is published
  // AFTER the binaries (i.e. to an already-existing version), so it must NOT be
  // gated on first-publish. A later binary publish sends no package_files, so it
  // won't clobber an existing listing.
  if (packageFilesText != null) {
    await env.BUCKET.put(packageFilesKey(manifest.id, manifest.version), packageFilesText, {
      httpMetadata: { contentType: "application/json; charset=utf-8" },
    });
  }

(If write-once immutability for the listing matters, additionally guard with a BUCKET.head(packageFilesKey(...)) check before the put — but don't keep it under !versionExists.)

🟡 Important

Test never exercises the two-publish ordering the workflow actually uses (workers/agent-hub/test/publish.test.ts:598)

All three new tests publish the zip + packageFiles in a single publish() call to a fresh env, so versionExists is always false — the exact state that hides the bug above. Add a test that mirrors the pipeline: publish a platform binary first, then publish the .zip + packageFiles as a second call to the same version, and assert entry.package is defined with the file list. That test fails today and will guard the fix.

it("surfaces package when the zip + file list are published AFTER the binaries (same version)", async () => {
  const env = makeEnv();
  await publish(env, {
    token: "tok_amd",
    manifestYaml: sampleManifest({ id: "two-step" }),
    artifact: "BINBYTES",
    filename: "email-agent-linux-x64",
  });
  await publish(env, {
    token: "tok_amd",
    manifestYaml: sampleManifest({ id: "two-step" }),
    artifact: "ZIPBYTES",
    filename: "agent-two-step-0.1.0.zip",
    packageFiles: filesJson,
  });
  const entry = (
    (await (await env.bucket.get("index.json"))!.json()) as CatalogIndex
  ).agents.find((a) => a.id === "two-step")!;
  expect(entry.package).toBeDefined();
  expect(entry.package!.files).toHaveLength(3);
});

🟢 Minor

size_bytes: 0 doc comment is now stale (workers/agent-hub/src/types.ts:216) — PackageInfo.size_bytes says "0 if the artifact isn't found", but toIndexEntry only constructs pkg when a .zip artifact is found (catalog.ts:382), so the 0 case is unreachable. Drop the "0 if…" clause to avoid implying a fallback that doesn't exist.

Strengths

• Worker/website/schema/README/types all updated together — the doc-sync discipline CLAUDE.md asks for is followed exactly.
• gen_package_files.py fails loudly on an empty/missing staging dir rather than emitting an empty list, and optionalPackageFiles rejects a malformed part with an actionable 400 — both align with the no-silent-fallbacks rule.
• The catalog only surfaces package when both the .zip artifact and its listing exist, and the website hides the whole section gracefully otherwise — good defensive pairing (the bug is purely that the listing never gets stored, not in this guard).

• publish.ts — moved the package_files write out of the !versionExists gate; keyed per version and guarded with a head() check (the immutable zip artifact 409s before reaching it anyway, so it can't be rewritten).
• publish.test.ts — new regression test: publish a binary first, then the zip + package_files in a second POST, assert index.json ends up with package populated. Verified it fails on the old code (expected undefined to be defined) and passes on the fix. Suite 63 → 64.
• release_agent_email.yml — edge fetch-verify the zip (200 + Content-Length == local size, same bounded retry as the binaries). The zip is SHA-verified on upload, but it isn't in binaries.lock.json so the fetch-CLI loop didn't cover it — a non-propagated/edge-blocked zip would have shipped a 404 button.

Verified clean: zip byte integrity (server + local SHA, fail-loud), graceful degradation for agents without a zip (package? optional through types/schema/page), XSS-safe rendering, no platform-name skew. worker: 64 tests pass, tsc clean.